[High] [Lens 7, 3, 2] — Every error response in the spec has a shape the server never sends

ErrorResponse publishes {status, message}, but 400/401/403/404/409/429 are all raised as APIException and routed through drf_standardized_errors (backend/middleware/exception.py:48), which emits {type, errors:[{code, detail, attr}]} — a disjoint shape. A generated SDK models both documented fields, finds them permanently absent on every failure, and has nothing to read a message from.

{status, message} fits only the hand-built 406/422/500 bodies (api_deployment_views.py:196-228).

Verified — the pinned handler run against this repo's own exceptions:

401 {'type':'client_error','errors':[{'code':'error','detail':'Unauthorized','attr':None}]}
400 {'type':'validation_error','errors':[{'code':'invalid','detail':'You must provide at least one file or presigned URL.','attr':None}]}

Corroborated in-repo by backend/middleware/test_exception.py:41-43 and frontend/src/hooks/useExceptionHandler.jsx:35.

Fix: the repo already ships drf-standardized-errors==0.15.0 with drf_standardized_errors/openapi.py for exactly this — use its AutoSchema as DEFAULT_SCHEMA_CLASS; or minimally redefine ErrorResponse to the handler's shape and keep {status, message} for 406/422/500 only.

[High] [Lens 7, 3] — error and status_api are published required non-nullable, but every successful 200 sends error: null

ExecutionResponse.__post_init__ (workflow_manager/workflow_v2/dto.py:72) forces falsy error to None, and DRF emits None verbatim for a bare CharField. So the happy path violates the published schema. status_api is null on both error returns in deployment_helper.py:300-307 and :361-367 — the 422 and 500 bodies.

Verified — the real serializer replayed over the real dataclass:

{'execution_status':'PENDING','status_api':'/deployment/...','error':None,'result':None}

A pydantic/Go/Java client raises on the success response.

The comment just above at :52-55 diagnoses this exact hazard for result and fixes it one field over — error is null more often than result is.

Fix: restate both as CharField(required=False, allow_null=True), regenerate.

[Medium] [Lens 7] — FileResult declares a metrics the server never emits and omits extracted_text which it does

Metrics live one level down at item["result"]["metrics"] — remove_result_metrics pops it off the inner dict (dto.py:163-169) — so no writer produces a top-level item["metrics"] and file_result.metrics is always empty.

Separately, promote_extracted_text sets item["extracted_text"] (dto.py:143-154) whenever include_extracted_text=true, and that field is absent here — so a typed client drops the payload the caller explicitly opted in for.

Verified — traced both API-result writers (endpoint_v2/destination.py:536-556, endpoint_v2/dto.py:137-146) and grepped every metrics/extracted_text write across backend/ and workers/.

Fix: drop metrics; add extracted_text = CharField(required=False, allow_null=True).

[Medium] [Lens 7] — execute can return 413/502/504 and arbitrary upstream statuses the spec does not declare

fetch_presigned_file raises 413 on oversize (deployment_helper.py:597-601), 504 on timeout (:665-668), 502 on connection error (:669-674), and — most consequentially — the upstream response's own status verbatim (:659-662, status_code = e.response.status_code).

So an expired S3 signature surfaces as a 403 whose spec description reads "No API key was supplied.", and an S3 404 as "No such active deployment." Undeclared statuses reach a generated client as an unmodelled response.

Fix: declare 413/502/504, and reword the 403/404 descriptions so they don't assert a cause the endpoint can't guarantee. Better still, normalise upstream statuses to a single 502 in fetch_presigned_file so the published contract is closed.

[Medium] [Lens 7, 16] — STATUS_DESCRIPTION tells callers to poll without saying the pending poll answers 422

"Poll while the execution is pending" reads as a 200-returning loop. api_deployment_views.py:230-246 starts response_status at HTTP_422_UNPROCESSABLE_ENTITY and raises it to 200 only on CeleryTaskState.COMPLETED.

Generated SDKs raise on 4xx by default, so the documented polling loop throws on every iteration until completion. The shape is declared (422: StatusResponse) so nothing is strictly wrong — the caller is simply not told the normal path is a non-2xx.

Fix: one sentence — a still-running execution answers 422 with the current status; only a completed one answers 200.

[Low] [Lens 13] — Two operation-level tests pass vacuously on an empty spec

Both this and test_operations_require_the_deployment_key (:97-98) loop over _operations(_committed()) with no non-emptiness guard, so a spec whose paths collapsed to {} satisfies them silently.

Today the file as a whole still catches that via :87 and :118 — but incidentally rather than by design. test_the_one_shot_read_is_documented_where_a_client_will_see_it already guards itself with assert reads at :118; these two didn't get the same treatment.

Fix: assert operations after materialising the list, or move the guard into _operations().

[Low] [Lens 13] — The drift gate's outcome depends on ambient API_DEPLOYMENT_PATH_PREFIX, enforced only by this docstring

Generated paths carry settings.API_DEPLOYMENT_PATH_PREFIX (backend/backend/base_urls.py:20), read from the environment at import with a default of deployment. A developer whose environment overrides it sees the drift test fail, regenerates as instructed, and commits a spec whose paths carry a private prefix — the test then passes on the wrong artifact and the downstream SDK repos are generated from it.

Low because nothing in-repo sets the variable (no .env sample, no compose file, and the rig's backend_test_env doesn't pin it) and a prefix change is visible in the specs/ diff.

Fix: assert the rendered path prefix equals the default, or override the setting for the duration of render_spec().

[Low] [Lens 13] — The --check branch and the write branch are exercised by nothing

--check is invoked by no CI job (ci-test.yaml runs only the tox tiers), no pre-commit hook, and no test. The actual drift gate in CI is test_committed_spec_matches_the_code, which reimplements the same comparison. So the branch the module docstring advertises as the drift command is untested, and the write branch's summary arithmetic at :94-103 is likewise unexercised.

Fix: exercise handle() via call_command (up-to-date, drifted, and write-to-tmp via --out), or drop --check and point the docstring at the pytest gate that actually runs.

(For the record, the drift gate itself is real — tests/groups.yaml:85-94 collects backend/** by glob, and CI shows unit-backend at 1009 passed. Only this branch is dead.)

[Low] [Lens 16] — This comment misstates spectacular's diagnostic severity and what it emits

The comment says spectacular "downgrades 'unable to guess serializer' to a warning and writes a plausible, wrong operation" (restated at test_docstudio_spec.py:55-57). In the pinned 0.30.0, that message is emitted through error() so it lands in _error_cache, not _warn_cache; and serializer resolution returns None, so the operation is published with no request body and a "No response body" response — not a guessed shape.

The guard is correct because it checks both caches. But a maintainer debugging a future failure looks in the wrong bucket and expects a fabricated schema that is never there.

Evidence: drf_spectacular/openapi.py:1269-1273 and :1498-1499.

Also here: docstudio (:23, :25) appears nowhere else in the repo, while the spec's own info.title is "Unstract API" — a maintainer has no path from either name to the other. Consider generate_api_deployment_spec / specs/api-deployment-oss.json, unless it's an established product name.

[Low] [Lens 16] — This comment states a consequence the PR's own guard makes impossible

The justification is that "leaving it in would publish guessed request and response shapes to every client generated from the spec." MCPServerView has no serializer_class/get_serializer, so without the exclusion spectacular emits unable to guess serializer into _error_cache — and render_spec(), added in this same PR, raises SpecGenerationFailed on any non-empty GENERATOR_STATS.

Nothing would be published; the command and the drift test would fail loudly. The stated risk is precisely the case the new guard exists to prevent, so the comment misrepresents the safety net a maintainer is standing on.

Fix: "…leaving it in would fail generation, since spectacular cannot guess a serializer for a JSON-RPC APIView and render_spec treats any diagnostic as fatal."